<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>11 - The X Window System</title>

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<link rev="made" href="mailto:www@openbsd.org">
<meta name="resource-type" content="document">
<meta name="description" content="the OpenBSD FAQ page">
<meta name="keywords" content="openbsd,faq">
<meta name="distribution" content="global">
<meta name="copyright" content="This document copyright 1998-2006 by OpenBSD.">
</head>

<body bgcolor="#ffffff" text="#000000">

<a href="../index.html">
<img alt="[OpenBSD]" src="../images/smalltitle.gif" border="0" height="30" width="141">    
</a>
<p>
<font color="#0000e0">
<a href="index.html">[FAQ Index]</a>
<a href="faq10.html">[To Section 10 - System Management]</a>
<a href="faq12.html">[To Section 12 - Hardware and Platform-Specific Questions]</a>
</font>

<h1><font color="#e00000">11 - The X Window System</font></h1>
<hr>

<p>
<h3>Table of Contents</h3>
<ul>
<li><a href="#Intro">11.1 - Introduction to X</a>
<li><a href="#ConfigX">11.2 - Configuring X</a>
<li><a href="#amd64i386">11.3 - Configuring X on amd64 and i386</a>
<li><a href="#StartingX">11.4 - Starting X</a>
<!-- li><a href="#TuningRes">11.9 - Tuning your monitor resolution under
  X</a -->
</li>
</ul>

<hr>

<p>
<a name="Intro"></a>
<h2>11.1 - Introduction to X</h2>

The X Window System (sometimes just called "X", other times, incorrectly
called "X Windows") is the environment which provides graphics services
to OpenBSD and other Unix-based systems.
However, by itself, X provides very little: one also must have a "Window
Manager", to present a user interface.
Most of the "personality" one will feel from X will be due to the 
window manager, rather than X itself.
OpenBSD ships with a free version of the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=fvwm&amp;sektion=1">fvwm(1)</a>
window manager, although you may wish to use any of the other window managers
that are in <a href="faq15.html">packages</a>.
Search using a key of "<tt>window manager</tt>" for a list of the many window
managers available.

<p>
X is considered a "client-server" structured protocol, however the 
terminology is sometimes confusing.
The computer with the graphics on the screen is the "X Server".
The application which directs the X server what to put on its screen
is the "X Client", even though it may be a much more powerful computer
in a data center.
This model can be used to have large, processor intensive applications
(X clients) running on a very powerful machine, using the X Server
running on a small, low power machine on your desk for their user 
interface.

<p>
It is possible to run X clients on a system without any graphical
support.
For example, one could have an application (the X client) running on an
mvme88k, displaying its output on an alpha's graphical display (the X
server).
Since X is a well-defined, cross-platform protocol, it is even possible
to have an X application running on (for example) a Solaris machine 
use an OpenBSD machine for its display.

<p>
The client and server can also be running on the same machine, and for 
most of this section, that will be the assumption.

<h3>11.1.1 - How much computer do I need to run X?</h3>
X itself is a pretty large program, a fast computer will be appreciated
if you are starting it and stopping it regularly.
However, once running, it performs pretty responsively on a very modest
computer.
To get responsive display performance on some platforms, even for just
text, you will want to run X.
These platforms, such as <a href="../sparc.html">sparc</a> and 
<a href="../sparc64.html">sparc64</a> were intended to be used with a
graphical interface, and the text console performance is very poor.

<p>
That being said, the point of running X is usually to run X
applications.
Some X applications are very lean, others will seemingly take and use
all the processor and RAM you can give them.
Of course, some users just like to use X to provide a large number of 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xterm&amp;sektion=1">xterm(1)</a>s,
which can be done on very modest hardware.

<h3>11.1.2 - Can I have any kind of graphics without X?</h3>
Assuming you won't accept
<a href="http://en.wikipedia.org/wiki/ASCII_Art">ASCII graphics</a>,
that requires some kind of framebuffer console driver.
Some operating systems provide this, but there is not currently one for
OpenBSD, nor is there much interest among developers for one.

<a name="ConfigX"></a>
<h2>11.2 - Configuring X</h2>
The configuration of X varies considerably from platform to platform.
In all cases, there will be instructions and other platform-specific
information in <tt>/usr/X11R6/README</tt> in the installed system.

<p>
Several platforms require the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xf86&amp;sektion=4">xf86(4)</a>
X aperture driver, which provides access to the memory and I/O 
ports of a VGA board and the PCI configuration registers required 
by the X servers.
This driver must be enabled before it is used, either by answering 
"yes" to this question during install:

<blockquote><pre>
Do you expect to run the X window System [no]
</pre></blockquote>

or by changing the value of <tt>machdep.allowaperture</tt> to the
appropriate non-zero value in <tt>/etc/sysctl.conf</tt> for your
platform, and rebooting the machine (this sysctl cannot be changed
after boot has been completed for security reasons).
There are security implications to this, so do not do this if you 
do not need it.


<h3>11.2.1 - alpha</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.alpha"
>/usr/X11R6/README</a> for alpha.

<p>
Set <tt>machdep.allowaperture=1</tt> in <tt>/etc/sysctl.conf</tt>.

<p>
The TGA and some VGA cards are supported.
No further configuration should be needed.

<h3>11.2.2 - amd64</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.amd64"
>/usr/X11R6/README</a> for amd64.

<p>
Set <tt>machdep.allowaperture=2</tt> in <tt>/etc/sysctl.conf</tt>.

<p>
X on amd64 often auto-configures very successfully, so no further
configuration is needed in many cases.
If further configuration is needed, use the 
<a href="#amd64i386">X&nbsp;-configure</a>
process <a href="#amd64i386example">below</a>.

<h3>11.2.3 - armish</h3>
No X servers, only X clients.

<h3>11.2.4 - hp300</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.hp300"
>/usr/X11R6/README</a> for hp300.

<h3>11.2.5 - hppa</h3>
No X server, only X clients.

<h3>11.2.6 - i386</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.i386"
>/usr/X11R6/README</a> for i386.

<p>
Set <tt>machdep.allowaperture=2</tt> in <tt>/etc/sysctl.conf</tt>.

<p>
Due to the incredibly wide range of video cards, mice, keyboards, and
other hardware, configuring an i386 system to run X can be exciting.
Exciting enough that a <a href="#amd64i386">separate section</a> is
provided.

<p>
Fortunately, things are not always as bad as they may seem -- in many
cases, X "Just Works" by invoking "startx".
In these cases, your hardware will be detected and queried for its
abilities, and X will run very well.


<h3>11.2.7 - landisk</h3>
No X servers, only X clients.

<h3>11.2.8 - luna88k</h3>
No X servers, only X clients.

<h3>11.2.9 - mac68k</h3>
No X servers, only X clients.

<h3>11.2.10 - macppc</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.macppc"
>/usr/X11R6/README</a> for macppc.
   
<p>
Set <tt>machdep.allowaperture=2</tt> in <tt>/etc/sysctl.conf</tt>.

<p> 
Supported Macintosh PPC systems can be run in one of two different ways:
"accelerated" and "framebuffer" (unaccelerated).

<p>
In the "framebuffer" mode, the system will be running with 8 bits per
pixel, and the video resolution is controlled by the Macintosh
environment, so you will probably want to keep a small MacOS section on
your disk to adjust these settings.
This mode has the advantage of "Just Working", however it can be 
frustratingly inflexible (for example, altering resolution may require
booting MacOS).

<p>
If your Macintosh has an ATI-based video system, it can run using an 
accelerated X server, which gives better performance and more control
in the OpenBSD environment.
The NVIDIA video cards in some macppc systems will also work in many
cases.
The README file has details on configuring the accelerated driver, start
using the sample file there.

<p>
While the README file details using the standard Apple one-button mouse
with X, unless you are using a laptop, it is highly recommended that you
just buy a modern third-party USB mouse.


<h3>11.2.11 - mvme68k</h3>
No X servers, only X clients.

<h3>11.2.12 - mvme88k</h3>
No X servers, only X clients.

<h3>11.2.13 - sgi</h3>
No X servers, only X clients.

<h3>11.2.14 - sparc</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.sparc"
>/usr/X11R6/README</a> for sparc.

<p>
With a single supported framebuffer, there is no configuration needed.
If you wish to use a multi-headed configuration, see the above README file
for details.

<p>
Resolution is controlled by the firmware before booting OpenBSD.

<h3>11.2.15 - sparc64</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.sparc64"
>/usr/X11R6/README</a> for sparc64.

<p>
There are a number of variations on these machines, you will need to
know what kind of bus your system has (PCI or SBus), what kind of port
your mouse is attached to (zstty, com, or USB/PS2), and what kind of
video card you have.
Start with the sample <tt>xorg.conf</tt> file in the <tt>README</tt>
file, then modify as indicated for your actual hardware and need.
<i>Do not expect the sample file to work unmodified on your machine!</i>

<h3>11.2.16 - vax</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.vax"
>/usr/X11R6/README</a> for vax.

<p>
The X server currently only works on VAXstation 4000 models with either a 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=lcg&amp;sektion=4&amp;arch=vax">lcg(4)</a>
or
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=lcspx&amp;sektion=4&amp;arch=vax">lcspx(4)</a>
framebuffer.

<h3>11.2.17 - zaurus</h3>
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/xenocara/distrib/notes/README.zaurus"
>/usr/X11R6/README</a> for zaurus.

<p>
No configuration needed, X "Just Works".


<p>
<a name="amd64i386"></a>
<h2>11.3 - Configuring X on amd64 and i386</h2>
The variety of hardware options on these platforms makes the X configuration
process "tricky".

<h3>11.3.1 - X.Org configuration</h3>
X.Org has made great improvements in making their servers "Just Work".
In many cases, it does Just Work without any <tt>/etc/X11/xorg.conf</tt>
file.
But not always, and sometimes, you need to customize something that does
work, anyway.

<p>
There are two programs that can be used to semi-automatically create a
configuration file for X.Org's i386 X servers.
Unfortunately, neither of them are guaranteed to create a usable
xorg.conf file.


<ul>
<li><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=Xorg&amp;sektion=1">Xorg(1)</a>
run in the "X -configure" mode will load all available video driver modules,
probes for other hardware, and based on what it finds, writes out a xorg.conf
file that may or may not work, but even if it does not work it may be a
useful starting point for creating one from scratch.

<li><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xorgconfig&amp;sektion=1">xorgconfig</a>
is another program that attempts to interactively create a xorg.conf
file, in a purely text-based application.

</ul>

In addition to the above applications, another time-honored way to
configure X is to use your favorite search engine to hunt for someone
else who already solved your problem.
While that's not a bad way, that method won't be emphasized here.

<p>

<a name="amd64i386example"></a>
<h3>11.3.2 - Our example machine</h3>
As a demonstration of setting up X, we will use an old Celeron 400MHz
system, with an AGP video slot.
The video card is an old AGP card, shown in the dmesg as:

<blockquote><pre>
vga1 at pci1 dev 0 function 0 "3DFX Interactive Banshee" rev 0x03
</pre></blockquote>

This is a once high-end video card, with 16M RAM, but is now mostly
unsupported on modern versions of "mainstream" operating systems.
The monitor attached to the system is a Sony Multiscan G400 19" CRT
monitor, and it would be nice to run this monitor at 1280x1024, with 
a decent refresh rate, and 24 bit color.

<p>
First, after installing OpenBSD with X (and making sure the aperture
driver is enabled in the kernel), let's see what X.Org's auto detection
and configuration does, after all, we might get lucky.
So, we simply log in and use the command
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=startx&amp;sektion=1">startx(1)</a>.
The screen goes blank for a few moments, the we get the X "checkerboard"
background, the "X" cursor, and then an xterm window.

<p>
It works!

<p>
More or less.
While the system is fully functional, it doesn't appear to have picked
up any of the capabilities of the monitor, and is running at what is
clearly a low resolution (640x480).
We hope to do better than this.
Much better, in fact.
This does mean we need to make our own xorg.conf file, however.

<p>
Let's use the "X -configure" process to generate a starting <tt>xorg.conf</tt>
file.
You will need to do this as root:
<blockquote><pre>
# <b>X -configure</b>
 [...]
Your xorg.conf file is /root/xorg.conf.new

To test the server, run 'X -config /root/xorg.conf.new'
</pre></blockquote>

By the way, the message is serious -- use the entire path to your 
<tt>xorg.conf.new</tt> file, even if it is sitting in your current
default directory.
Failing to do so will result in
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=X&amp;sektion=7">X(7)</a>
not finding the file, and it will silently use the default
configuration, which may have nothing to do with the file you are
currently working with.
This can set back your troubleshooting quite a bit.
Trust us on this.

<p>
Let's do as it says, and see what we get:
<blockquote><pre>
# <b>X -config /root/xorg.conf.new</b>
</pre></blockquote>

Now, all we get is a black screen.
Things had started out so well...

<p>
This might be a really good time to talk about ways of 
exiting X when started in this way.
In order of preference:
<ul>
<li><b>CTRL-ALT-Backspace</b>:  This hopefully causes X to immediately
terminate, along with all X applications that are running.
Of course, during the configuration process, you don't have any 
applications running, so this is not a problem (and in fact, at
this point, this is your <i>best</i> way to exit X).
<li><b>SSH into the box</b>, and 
"<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pkill&amp;sektion=1">pkill</a>
Xorg", which may kill the X process, and may return you to a usable console.
<li><b>SSH into the box</b> and reboot it.
<li><b>Reset or power button.</b>  Sometimes things go really bad.
Yes, it is usually good to get X running before you load critical
applications on the system.
Sometimes, a bad X configuration will hang the entire machine to the 
point that only a hard reset will resolve the problem.
</ul>

Fortunately for us, CTRL-ALT-Backspace does the job here, and we
are returned to a command prompt.
So now we need to see if we can figure out what is wrong.
First, we should look at what Xorg thinks is going on, and that is 
recorded in the file <tt>/var/log/Xorg.0.log</tt>.
In this case, it appears that X thinks all is running fine, there are no
obviously significant errors shown in the log (lines that start with an
"<tt>(EE)</tt>" are errors).

<p>
Here is where knowing your hardware comes in handy.
Attaching this system to a different monitor while it is showing the
blank screen produces a "Sync. Out of Range" message on the display.
So, apparently the configuration X gave us will not run on this monitor,
and may not run on ANY monitor, if a video mode was selected that isn't
possible for this particular card (keep in mind, X is looking at the
chips on the card, and what they are potentially capable of, not how the
manufacturer put it all together).
Different monitors will do different things when the timing is way off,
some will attempt to display what they can, others will drop to power 
saving mode, some will make horrible noises, some will display useful
messages on the screen.
This monitor seems to do none of the above.
A note is made to NOT use this monitor for initial X configuration in
the future.

<p>
Looking through the generated xorg.conf.new file, we see this:
<blockquote><pre>
Section "Monitor"
        #DisplaySize      370   270     # mm
        Identifier   "Monitor0"
        VendorName   "SNY"
        ModelName    "SONY CPD-G400"
 ### Comment all HorizSync and VertSync values to use DDC:
        HorizSync    30.0 - 107.0
        VertRefresh  48.0 - 120.0
        Option      "DPMS"
EndSection
</pre></blockquote>

As a test, let's try using DDC ("Data Display Channel", a way the
monitor can tell the computer and video card what it is capable of), and
see what happens.
This time, we get the X mesh pattern and the moving cursor, which is all
we expect when invoking X in this way (we terminate X using the
CTRL-ALT-Backspace trick above).
It is (again) a very low resolution, but it is working, so we can be
pretty sure we have a timing and resolution problem.
We'll restore the "HorizSync" and "VertRefresh" lines as they were,
as we have verified this monitor's specs through a bit of Internet
searching.

<p>
Let's try to force Xorg to a particular resolution, and see if we have any
luck.
In the <tt>Section "Screen"</tt> part of the xorg.conf file, we want to add 
a couple lines.
The added lines are shown in bold:

<blockquote><pre>
Section "Screen"
        Identifier "Screen0"
        Device     "Card0"
        Monitor    "Monitor0"
<b>        DefaultDepth   24</b>
        SubSection "Display"
                Viewport   0 0
                Depth     1
        EndSubSection
        SubSection "Display"
                Viewport   0 0
                Depth     4
        EndSubSection
        SubSection "Display"
                Viewport   0 0
                Depth     8
        EndSubSection
        SubSection "Display"
                Viewport   0 0
                Depth     15
        EndSubSection
        SubSection "Display"
                Viewport   0 0 
                Depth     16
        EndSubSection
        SubSection "Display"
                Viewport   0 0
                Depth     24
<b>                Modes	"1280x1024"</b>
        EndSubSection
EndSection
</pre></blockquote>

These two changes tell X we want to use a 24 bit display depth, and 
for 24 bit depths, we want the resolution 1280x1024.
As no other resolution is listed for "Depth 24", the system will 
be forced to that resolution.

<p>
We test as above, and...  SUCCESS!
We have what appears to be a very nice, high resolution display.
Note that ALL that is expected is a mesh pattern (very good for seeing
how good your monitor REALLY is and also great for calibrating LCD
displays, called the
"<a href="http://www.openbsd.org/cgi-bin/cvsweb/xenocara/data/bitmaps/root_weave">root
weave</a>") and a movable cursor.
It is not intended to be functional at this point.

<p>
Now, we want to install this xorg.conf file so we can see how well we
are really doing with usable running of X.

<blockquote><pre>
# cp xorg.conf.new /etc/X11/xorg.conf
</pre></blockquote>

We can now try X using the normal startx(1) command.
It works!

<p>
It would probably be good to verify that we are at the resolution and
color depth we desire, and also that we are running at a respectable
refresh rate.
We can do that with the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xrandr&amp;sektion=1">xrandr(1)</a>
and 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xdpyinfo&amp;sektion=1">xdpyinfo(1)</a>
commands.
Among other things, xdpyinfo(1) tells us:
<blockquote><pre>
    [...]
screen #0:
  print screen:    no
  dimensions:    1280x1024 pixels (433x347 millimeters)
  resolution:    75x75 dots per inch
  depths (7):    24, 1, 4, 8, 15, 16, 32
  root window id:    0x44
  depth of root window:    24 planes
    [...]
</pre></blockquote>

So, yes, we are running at 1280x1024 with a depth of 24 planes (bits).

<p>
xrandr(4) tells us:
<blockquote><pre>
 SZ:    Pixels          Physical       Refresh
*0   1280 x 1024   ( 433mm x 347mm )  *85   75   60  
 1   1280 x 960    ( 433mm x 347mm )   85   60  
    [...]
</pre></blockquote>

which tells us we are running with an 85Hz refresh rate, so this should
be a very comfortable setting for most users.

<p>
<h3>11.3.3 - What if it isn't that "easy"?</h3>
Sometimes, things just don't go together.
Here are some tips.

<ul>
<li>Read the man page for the X server you are using.
In our example, the <tt>/var/log/Xorg.0.log</tt> file, we can see X is 
using TDFX as the driver, so that would be the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=tdfx&amp;sektion=4">tdfx(4)</a>
man page.
You will often find tips, limitations, and options for configuring your
video card.
These vary from driver to driver, so don't assume you don't need to read the 
man page for the driver you are using now because you read a different one
before.

<li>Try different monitors.
As we discovered in our above example, different monitors will often give 
different clues as to what might be wrong.

<li>Try the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=vesa&amp;sektion=4">vesa(4)</a>
X driver.
This is definitely a "last choice" for performance reasons, but it works
on almost all video cards, including those for which none of the "better"
X server drivers will work with.

<li>Use different hardware.
If you have choice on the video card to use, try some others.


</ul>

<a name="StartingX"></a>
<h2>11.4 - Starting X</h2>
There are two common ways to run X:

<h3>11.4.1 - On Demand:</h3>
Log in to a console as normal, then run
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=startx&amp;sektion=1">startx(1)</a>.

<h3>11.4.2 - Boot directly into X:</h3>
This is done using
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xdm&amp;sektion=1">xdm(1)</a>,
the X Display Manager.
xdm(1) is started as root, normally by <a href="faq10.html#rc">rc</a>,
and presents a login prompt.
Upon successful login, it starts an X session for that user.
If or when that X session should be terminated (including by hitting 
CTRL-ALT-Backspace), xdm(1) will return, prompting the user to login again.
For this reason, do NOT attempt to start xdm(1) from
<tt>/etc/rc.conf.local</tt> until you have verified X works as you wish,
or your machine may become very difficult to manage!
(worst case: boot single user, as if you <a href="faq8.html#LostPW">lost
your password</a>, and edit out the xdm_flags line in your
<tt>/etc/rc.conf.local</tt> file.)

<p>
On some platforms, you will need to disable the console
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=getty&amp;sektion=8">getty(8)</a>
to use xdm(1).


<p>
<!-- a name= "TuningRes"></a>
<h2>11.9 - Tuning your monitor resolution under X</h2>

<i>Note: Most users do NOT need to worry about manually creating a 
ModeLine in modern versions of X.
HOWEVER, sometimes it is needed for unusual situations.</i>

<p>
Getting an X server working at an acceptable resolution with many multi-sync
monitors is possible.  If anyone has tried to do this with the standard
xorgconfig or XF86Setup utilities, they probably didn't get the best possible
results.  One of the more painful aspects is simply getting your monitor running
with your preferred resolution,
and then
getting the vertical scan rate set to at least 72-75 Hz,
a rate where the screen flicker is much less visible to humans.  
Conversely, what if you are trying to set the vertical scan rate so it is very low?
You can set it at 50 Hz so that it can be captured on to video without flicker,
but the methods to do this are non-obvious with the standard X tools and
documentation.

<p>
Finally, at the resolutions many people normally use with inexpensive VGA monitors
(800x600, 1024x768, 1152x900,
1280x1024), it is possible (at least on newer monitors) to use vertical scan rates of
85Hz and above, to achieve an extremely clean, palatable picture.
The X server has a mechanism which allows you to describe in detail the video
mode you want to use, this is the ModeLine.  A ModeLine has four sections, a single number for the pixel clock,
four numbers for horizontal timings, four numbers for vertical timings,
and an optional section with a list of flags specifying other characteristics
of the mode (such as Interlace, DoubleScan, and more... see the
xorg.conf(5) manual page for more ModeLine details).

<p>
Generating a ModeLine is a black art... Luckily, there are several scripts
which can do this for you.  One is <a href="http://koala.ilog.fr/cgi-bin/nph-colas-modelines">
Colas XFree86 ModeLine Generator</a>.  Another is
<a href="http://xtiming.sourceforge.net/">The XFree86 Modeline Generator</a>
hosted at SourceForge, and there are several others available on
<a href="http://freshmeat.net/search/?q=modeline">Freshmeat</a>.
Before you can use these ModeLine generators, you need to figure
out the vertical
and horizontal sync limits for your monitor.  This is often documented
in the manual, or on the manufacturer's web site.  If you can't find
either of those, simply search the web for the monitor make and model,
several people have been kind enough to compile lists with this information.

<p>
For example, say you have a Dell D1226H monitor.  You searched in agony
at Dell's web site to find that it has a 30-95 kHz horizontal scan range,
and a 50-160 Hz vertical scan range.  Visit the ModeLine generator page,
enter this information.  Next, you need to enter the minimum
vertical scan rate you want.  Any rate at or above 72 Hz should generally have low
visible flicker.  As you go higher, the clearer and crisper your screen
image becomes.  

<p>
With all of these bits of information, the script will generate a ModeLine
for every possible 4x3 resolution which your monitor can support, above
the minimum vertical scan rate which you enter.  If someone enters the Dell specs above
and a 75 Hz vertical scan minimum, the script gives out something like the
following:

<pre>
ModeLine "320x240" 20.07 320 336 416 448 240 242 254 280 #160Hz
ModeLine "328x246" 20.86 328 344 424 456 246 248 260 286 #160Hz
...
ModeLine "816x612" 107.39 816 856 1056 1136 612 614 626 652 #145Hz
ModeLine "824x618" 108.39 824 864 1064 1144 618 620 632 658 #144Hz
ModeLine "832x624" 109.38 832 872 1072 1152 624 626 638 664 #143Hz
...
ModeLine "840x630" 109.58 840 880 1080 1160 630 632 644 670 #141Hz
ModeLine "848x636" 110.54 848 888 1088 1168 636 638 650 676 #140Hz
...
ModeLine "1048x786" 136.02 1048 1096 1336 1432 786 788 800 826 #115Hz
ModeLine "1056x792" 136.58 1056 1104 1344 1440 792 794 806 832 #114Hz
ModeLine "1064x798" 137.11 1064 1112 1352 1448 798 800 812 838 #113Hz
...
ModeLine "1432x1074" 184.07 1432 1496 1816 1944 1074 1076 1088 1114 #85Hz
ModeLine "1576x1182" 199.86 1576 1648 2008 2152 1182 1184 1196 1222 #76Hz
ModeLine "1584x1188" 198.93 1584 1656 2016 2160 1188 1190 1202 1228 #75Hz
</pre>

<p>
Now, this monitor claims to do 1600x1200 @ 75 Hz, but the script does not
say this is within 75 Hz.  So, if you really want exactly 1600x1200, 
go down a notch with your minimum vertical rate... (Here, we go down
to 70 Hz)

<pre>
ModeLine "1592x1194" 197.97 1592 1664 2024 2168 1194 1196 1208 1234 #74Hz
ModeLine "1600x1200" 199.67 1600 1672 2032 2176 1200 1202 1214 1240 #74Hz
ModeLine "1608x1206" 198.65 1608 1680 2040 2184 1206 1208 1220 1246 #73Hz
ModeLine "1616x1212" 197.59 1616 1688 2048 2192 1212 1214 1226 1252 #72Hz
ModeLine "1624x1218" 199.26 1624 1696 2056 2200 1218 1220 1232 1258 #72Hz
ModeLine "1632x1224" 198.15 1632 1704 2064 2208 1224 1226 1238 1264 #71Hz
ModeLine "1640x1230" 199.81 1640 1712 2072 2216 1230 1232 1244 1270 #71Hz
ModeLine "1648x1236" 198.64 1648 1720 2080 2224 1236 1238 1250 1276 #70Hz
</pre>

<p>
Here, we see the monitor really does 1600x1200 @ 74 Hz when the dot clock
(bandwidth) is limited to 200MHz.  Set the bandwidth according to the
limits defined by the monitor.

<p>
Once you have your ModeLines, put them into your /etc/X11/xorg.conf file. 
Comment out the old ModeLines, so that you can use them again if the new ones
don't work.
Next, choose what resolution you actually want to run at.   First,
figure out if X is running in accelerated mode (which it does with most video
cards), so you know which <tt>"Screen"</tt> section of the xorg.conf to modify.
Or, just modify all of the Screen sections.

<pre>
Section "Screen"
   Driver          "Accel"
   Device          "Primary Card"
   Monitor         "Primary Monitor"
   DefaultColorDepth 32
   SubSection "Display"
      Depth        32
      Modes        "1280x1024" "1024x768"
   EndSubSection
</pre>

<p>
The first resolution you see after the "Modes" keyword is the resolution that
X is going to start in.  By pressing CTRL-ALT-KEYPAD MINUS, or CTRL-ALT-KEYPAD
PLUS, you can switch between any resolutions that you list here.  According
to the section above, X will try to start in 32-bit color mode (via
the DefaultColorDepth directive, without it X will start in 8-bit color mode.)
The first resolution it will try to use is 1280x1024 (it follows the order
of the Modes line.)  Note that "1280x1024" is just a label for the values in
the ModeLine.

<p>
Note that the ModeLine generator script has options to relax its timings for older
or smaller monitors, and also has the ability to provide ModeLines for
specific resolutions.  Depending on the type of hardware you have, it
may not be very easy to use with the default options.  If the picture is
too tall, too wide, or too small, or is shifted horizontally or vertically,
and the controls of the monitor aren't enough to correct its appearance,
one can use xvidtune(1) to adjust the ModeLine to better fit with the
monitor's timings.

<p>
On most modern monitors, there is no fixed limit on the bandwidth, thus
they are often not listed anymore in the specs. What happens is that the
more you go up in bandwidth, the fuzzier the screen image becomes.
So you may want to put in the bandwidth of your card (also named
"dotclock") to test (you cannot damage your monitor this way), and go
progressively down in bandwidth until you have a nice crisp image.

<p>
If this seems needlessly complex, that's because it is.  X.Org addresses
this, and makes this process much easier since it has several built-in
modes and is capable of reading back capabilities from "plug and play" monitors
through DDC and DDC2.

<p>
You can download the Colas XFree86 ModeLine Generator script at:
<a href="http://koala.ilog.fr/ftp/pub/Klone/">http://koala.ilog.fr/ftp/pub/Klone/</a>.
You need to grab the Klone interpreter, and compile it.  It is in the
ports as <tt>lang/klone</tt>.  The scripts
exist under the scripts directory in the Klone distribution.  (The
port installs them to /usr/local/lib/klone/scripts.)

<p>
There are two versions of the script included, the first is a CGI version identical
to the web page above.  The second is a non-CGI version
which will take your complete xorg.conf file, decode the monitor specs that
you entered into xorgconfig/XF86Setup (Now, think, did you actually
enter the specs for your monitor or just choose generic ones?),
and fix the existing ModeLines accordingly. 

<p -->
<font color= "#0000e0">
<a href= "index.html">[FAQ Index]</a>
<a href= "faq10.html">[To Section 10 - System Management]</a>
<a href= "faq12.html">[To Section 12 - Hardware and Platform-Specific Questions]</a>
</font>

<p>
<hr>
<a href= "index.html"><img height= "24" width= "24" src= "../images/back.gif" border= "0" alt="[back]"></a>
<a href="mailto:www@openbsd.org">www@openbsd.org</a>
<br>
<small>$OpenBSD: faq11.html,v 1.75 2008/07/08 00:00:59 nick Exp $</small>
</body>
</html>
